@paradigma-inc/flywheel 0.1.19 → 0.1.26

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

@@ -9,10 +9,10 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - 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.
+- `stage_commit` (Stage and commit): Stage/commit 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` (Compute): Lease ownership, token-scoped control, 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.
 
@@ -50,10 +50,12 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_get_campaign_snapshot` (read; scopes: `read`; core surface; binding: `operation`)
 - `flywheel_list_audit` (read; scopes: `read`; full-surface only; binding: `operation`)
 
-### Node lifecycle
+### Node stage and commit
 
-- `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_new_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; full-surface only; 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`)
@@ -80,6 +82,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 ### Compute and budgets
 
 - `flywheel_compute_list_options` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_funding` (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`)
@@ -132,10 +135,12 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `GET /mcp/nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
 - `GET /mcp/nodes/{node_id}/audit` -> `flywheel_list_audit`
 
-### Node lifecycle
+### Node stage and commit
 
-- `POST /mcp/nodes/stage/create` -> `flywheel_stage_node_create`
-- `PATCH /mcp/nodes/{node_id}/stage/update` -> `flywheel_stage_node_update`
+- `POST /mcp/nodes/commit-new` -> `flywheel_commit_new_node`
+- `POST /mcp/nodes/{node_id}/stage/lease/acquire` -> `flywheel_acquire_stage_lease`
+- `POST /mcp/nodes/{node_id}/stage/lease/heartbeat` -> `flywheel_heartbeat_stage_lease`
+- `POST /mcp/nodes/{node_id}/stage/lease/release` -> `flywheel_release_stage_lease`
 - `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`
@@ -161,7 +166,8 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 
 ### Compute and budgets
 
-- `GET /mcp/nodes/{node_id}/compute/options` -> `flywheel_compute_list_options`
+- `GET /mcp/compute/catalog` -> `flywheel_compute_list_options`
+- `GET /mcp/compute/funding` -> `flywheel_compute_funding`
 - `GET /mcp/compute/status` -> `flywheel_compute_status`
 - `GET /mcp/compute/connection` -> `flywheel_compute_connection`
 - `POST /mcp/approval-sessions/heartbeat` -> `flywheel_approval_session_heartbeat`
@@ -173,7 +179,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `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`
+- `tool-mediated` -> `flywheel_compute_acquire`
 - `POST /mcp/compute/release` -> `flywheel_compute_release`
 - `POST /mcp/compute/release-all` -> `flywheel_compute_release_all`
 

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

@@ -12,13 +12,6 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - 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.
-- Node lifecycle semantics are interface-agnostic (`stage_node_create`, `stage_node_update`, `commit_node`); MCP tools are one projection of this shared contract.
-- Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision`, and handle `409 conflict` with explicit reconciliation.
-- Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
-- Commit is finalize-only: commit requests require `expected_revision` and may optionally override `summary`; committed node state must still satisfy strict contract (`summary`/`outcome`, `empirical+completed` requires artifacts or `no_artifacts_reason`, `insight` requires non-empty insights).
-- When code is involved, pass `repo_url`/`branch_name`/`head_commit_sha` and align git structure with graph topology where practical (without forcing one-to-one mapping).
-- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
-- Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
 - 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`.
 
@@ -47,11 +40,13 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `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 lifecycle
+### Node stage and commit
 
-- `flywheel_stage_node_create` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/stage/create`; full-surface only): Stage creation of a new Flywheel node.
-- `flywheel_stage_node_update` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{node_id}/stage/update`; core surface): Stage mutable node fields, including content/readme text, with optimistic locking; use `no_artifacts_reason` when empirical completed nodes intentionally have no artifacts.
-- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/commit`; core surface): Commit a node with contract validation.
+- `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).
@@ -76,21 +71,22 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 ### 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. 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. Only leases owned by the current user are connectable. Pass lease_id or node_id to disambiguate when needed.
+- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /mcp/compute/catalog`; core surface): List managed compute catalog options. This endpoint is catalog-only and excludes grant/budget funding fields.
+- `flywheel_compute_funding` (read; scopes: `compute`; HTTP: `GET /mcp/compute/funding`; core surface): Read grant-scoped compute funding context for a specific compute_grant_id.
+- `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. Optionally include grant approval bindings for each session.
-- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/expire`; core surface): Expire the current compute-grant approval session and release its active leases.
-- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Request budget approval and return approval_url + request_id for user confirmation before managed compute acquisition.
+- `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: `POST /mcp/nodes/{node_id}/compute/acquire`; 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 heartbeats and 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.
-- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release-all`; core surface): Asynchronously release all active managed compute leases for the current user.
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Acquire managed compute 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 and optional context_node_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
 
@@ -113,15 +109,15 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 ### Safe Node Update
 
 1. `flywheel_get_node`: Read latest node state before mutating fields.
-2. `flywheel_stage_node_update`: Stage changes with fresh expected_revision and resolve 409 conflicts explicitly.
-3. `flywheel_commit_node`: Commit once terminal and contract-complete.
+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_stage_node_create`: Create a staged node, then set empirical fields before execution.
-2. `flywheel_stage_node_update`: Set `kind=empirical`, `hypothesis`, and summary fields with fresh `expected_revision`.
-3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval first. Response status is `approval_required`.
-4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status. `approval_required` is a response state, not a request parameter.. 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_approval_sessions`: After approval, list approval sessions with include_approvals=true and use the active `compute_grant_id` for the current approval_session_id.
+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.
@@ -135,19 +131,20 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - `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_stage_node_update`: update in-progress node fields (title/content/summary, kind/outcome/hypothesis/insights/no_artifacts_reason), always with fresh `expected_revision`.
+- `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), to detect any active user lease 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`); this returns `approval_url` + `request_id` when interactive approval is needed.
-- `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable.
-- `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).
-- `flywheel_compute_release`: release compute when no longer needed.
-- `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution lifecycle.
+- `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`. This is a catalog-only read and excludes grant/budget money fields.
+- `flywheel_compute_funding`: read grant-scoped funding context (`grant_cents`, `remaining_cents`, backing budget fields) for the selected `compute_grant_id` before acquire.
+- `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_node`: finalize staged node state once terminal and contract-complete (optional summary override 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-prove/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: flywheel-prove
+description: Local Lean theorem proving and formalization pipeline.
+---
+
+# flywheel-prove
+
+## When To Use
+
+Use this skill when you need to scaffold or run a local Lean theorem proving pipeline in a repo.
+Use it for formalization tasks that require filling `sorry` placeholders and proving statements in Lean.
+Use it when converting theorem-heavy source material into Lean modules, iterating on failed verification, or producing reproducible proof artifacts for review.
+
+## Prerequisite (Required)
+
+Before running the pipeline, ensure both `uv` and the Lean toolchain manager `elan` are installed on the local machine.
+
+- If `uv` is missing, bootstrap it by OS:
+  - macOS/Linux:
+    ```bash
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    ```
+  - Windows (PowerShell):
+    ```powershell
+    irm https://astral.sh/uv/install.ps1 | iex
+    ```
+
+- If `elan` is missing, bootstrap it by OS:
+  - macOS/Linux:
+    ```bash
+    curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh -s -- -y
+    ```
+  - Windows (PowerShell):
+    ```powershell
+    Invoke-WebRequest -Uri https://raw.githubusercontent.com/leanprover/elan/master/elan-init.ps1 -OutFile elan-init.ps1
+    powershell -ExecutionPolicy Bypass -File .\elan-init.ps1
+    ```
+
+Then verify:
+
+```bash
+uv --version
+elan --version
+lean --version
+lake --version
+```
+
+## Workflow
+
+1. Scaffold pipeline into the current repository:
+
+   ```bash
+   python <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
+   cd <repo-root>/theorem_pipeline
+   ```
+
+   `<skill-root>` is the directory that contains this `SKILL.md`.
+   `pypdf` is installed via template dependencies during `uv sync`; do not use `pdftotext`.
+
+2. Move into `<repo-root>/theorem_pipeline` and initialize:
+
+   ```bash
+   uv run -m tproof.cli doctor
+   uv run -m tproof.cli init --build
+   ```
+
+   Warning: `init --build` may take a few minutes on first run (toolchain/dependency fetch + first build). It is typically much faster on later runs when proving multiple artifacts in the same workspace.
+   Requirement: Before executing `uv run -m tproof.cli init --build`, the agent MUST explicitly warn the human user in-chat about this first-run delay.
+
+3. Normalize source context before formalization (conditional by input type).
+   - First, identify the source type from the user request.
+   - If the source is a PDF:
+     - Extract text with `pypdf` (do not use `pdftotext`), enforce UTF-8-safe output, and sanitize mojibake.
+     - Required artifact A (full cached extraction):
+       - `theorem_pipeline/workspace/contexts/<pdf_stem>.txt`
+       - Example: `paper.pdf -> theorem_pipeline/workspace/contexts/paper.txt`
+     - Required artifact B (theorem-focused excerpt):
+       - `theorem_pipeline/workspace/contexts/<theorem_slug>_source_excerpt.txt`
+       - Example: `proposition2_source_excerpt.txt`
+     - Keep both artifacts. The full extraction is a reusable cache for proving multiple theorems from the same paper; do not reconvert the PDF if the cached full extraction already exists and is still valid.
+   - If the source is not a PDF (for example: prompt text, `.txt`, `.md`, `.tex`, or fetched online content):
+     - Skip PDF conversion.
+     - Use the source exactly as requested by the user.
+     - Store the normalized local source artifact under `theorem_pipeline/workspace/contexts/` (for example, `<theorem_slug>_source.txt`), and optionally store a focused excerpt as `<theorem_slug>_source_excerpt.txt` when useful.
+   - Explicit ASCII rewrites of common symbols are allowed (for example: `R-field -> Real`, `norm-notation -> norm x`, `leq -> <=`, `and -> /\\`, `arrow -> ->`).
+
+4. Start a run:
+
+   ```bash
+   uv run -m tproof.cli start-run --prompt-file ./workspace/prompts/fill_sorries.txt
+   ```
+
+5. Formalization contract (required before proving): define
+   - theorem name,
+   - exact assumptions,
+   - target conclusion,
+   - whether corollaries are required (`help` / `match` / `upper-bound`).
+
+6. Use required model routing:
+   - Mathematical proof work: a deep-thinking model suitable for complex mathematical reasoning.
+   - Programming/scripting/reporting work: a smaller coding-oriented model for automation and logs.
+
+7. Artifact destination (mandatory, no exceptions):
+   - Final theorem artifacts MUST live under:
+     - `theorem_pipeline/workspace/lean_project/ProofWorkspace/Final/`
+   - Never write final artifacts under `workspace/staging/` (forbidden).
+   - Lean module files must use Lean-safe filenames (no hyphens), for example:
+     - full formal proof file: `<Name>Full.lean`
+     - human-readable sketch file: `<Name>Sketch.md`
+     - example pair:
+       - `ProofWorkspace/Final/Proposition1Full.lean`
+       - `ProofWorkspace/Final/Proposition1Sketch.md`
+
+8. Fast iteration loop:
+
+   ```bash
+   lake env lean <tmpfile>
+   ```
+
+   Use `<tmpfile>` for quick local iterations, then copy finalized proof into the target module.
+
+9. Sidecar proof sketch (required):
+   - For each produced full proof file `<Name>Full.lean`, create a sibling sketch file `<Name>Sketch.md` in `ProofWorkspace/Final/`.
+   - Keep the sketch human-readable for paper-writing: theorem statement, assumptions, proof idea/structure, and how corollaries follow.
+   - In sketch files, write mathematics using LaTeX formulas with dollar syntax (`$...$` for inline and `$$...$$` for display).
+   - This is safe in the Lean project because the pipeline reindex/verification scans only `*.lean`.
+
+10. Reindex and verify:
+
+    ```bash
+    uv run -m tproof.cli reindex
+    uv run -m tproof.cli verify
+    ```
+
+    `verify` must pass with no unresolved `sorry` and no `.lean`/`.md` final artifacts under `workspace/staging/`.
+
+11. Mark run status:
+
+    ```bash
+    uv run -m tproof.cli set-status <run_id> COMPLETE --note "verified locally"
+    ```
+
+## Completion Checklist
+
+Always report:
+
+- theorem file path,
+- sidecar proof sketch path,
+- final artifact directory path (`theorem_pipeline/workspace/lean_project/ProofWorkspace/Final/`),
+- source context artifact path(s):
+  - if PDF input: full extraction path (`<pdf_stem>.txt`) and excerpt path (`<theorem_slug>_source_excerpt.txt`);
+  - otherwise: normalized source path used (for example `<theorem_slug>_source.txt`) and excerpt path if created,
+- theorem names,
+- verify log path,
+- run id/status.
+- Add one extra final report line (without changing existing format): `SUCCESS` or `FAIL: <reason>`.
+
+## Resources
+
+- Use `scripts/scaffold_pipeline.py` to install the full local pipeline template.
+- Use `references/workflow.md` for detailed run loop guidance.
+- Use `assets/pipeline_template/` as the canonical implementation source copied into each repository.
+- Use `agents/interface.yaml` as the universal skill interface metadata.

package/skills/flywheel-prove/agents/interface.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flywheel Prove"
+  short_description: "Local Lean theorem proving pipeline"
+  default_prompt: "Use $flywheel-prove to scaffold and run a local Lean theorem proving pipeline."

package/skills/flywheel-prove/assets/pipeline_template/bin/tproof

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+set -eu
+uv run -m tproof.cli "$@"

package/skills/flywheel-prove/assets/pipeline_template/bin/tproof.cmd

@@ -0,0 +1,2 @@
+@echo off
+uv run -m tproof.cli %*

package/skills/flywheel-prove/assets/pipeline_template/logs/.gitkeep

@@ -0,0 +1 @@
+

package/skills/flywheel-prove/assets/pipeline_template/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "tproof"
+version = "0.1.0"
+description = "Local Lean theorem proving pipeline"
+requires-python = ">=3.10"
+dependencies = [
+  "typer>=0.24.1",
+  "rich>=14.3.3",
+  "pypdf>=4.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100

package/skills/flywheel-prove/assets/pipeline_template/scripts/smoke_test.cmd

@@ -0,0 +1,2 @@
+@echo off
+uv run -m tproof.cli smoke-test %*

package/skills/flywheel-prove/assets/pipeline_template/scripts/smoke_test.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+set -eu
+uv run -m tproof.cli smoke-test "$@"

package/skills/flywheel-prove/assets/pipeline_template/src/tproof/__init__.py

@@ -0,0 +1 @@
+"""Local Lean theorem proving pipeline."""