@paradigma-inc/flywheel 0.1.19 → 0.1.25

package/skills/flywheel-prove/references/workflow.md

@@ -0,0 +1,193 @@
+# Workflow
+
+## 0. Prerequisite: Local Toolchain Bootstrap
+
+Ensure the host has:
+- `uv`
+- `elan` (Lean toolchain manager)
+
+If `uv` is missing, install 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, install 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
+  ```
+
+Verify bootstrap before running pipeline commands:
+
+```bash
+uv --version
+elan --version
+lean --version
+lake --version
+```
+
+## 1. Scaffold Pipeline Into Repo
+
+```bash
+python <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
+```
+
+`<skill-root>` is the directory that contains this skill.
+
+Creates `<repo-root>/theorem_pipeline` with:
+- `workspace/lean_project/` canonical cumulative Lean project
+- `data/runs/` run metadata and proof briefs
+- `logs/` local Lean verification logs
+- `src/tproof/` local CLI orchestration
+
+## 2. Initialize Lean Toolchain
+
+From `theorem_pipeline/`:
+
+```bash
+uv run -m tproof.cli doctor
+uv run -m tproof.cli init --build
+```
+
+Warning: `init --build` can take several minutes the first time (toolchain/dependency download and initial compilation). Subsequent proving runs in the same workspace are usually much faster because those artifacts are cached.
+Operator requirement: Before running `uv run -m tproof.cli init --build`, explicitly notify the human user in-chat about this first-run delay.
+
+Pinned versions:
+- Lean toolchain: `leanprover/lean4:v4.28.0`
+- Mathlib hash: `8f9d9cff6bd728b17a24e163c9402775d9e6a365`
+
+## 2.1 Source Context Normalization (Conditional)
+
+Handle source ingestion based on user-provided input type.
+
+If input is a PDF:
+- Use `pypdf` (not `pdftotext`) and sanitize mojibake with UTF-8-safe output before theorem formalization.
+- Required output A (full cached extraction):
+  - `theorem_pipeline/workspace/contexts/<pdf_stem>.txt`
+  - Example: `paper.pdf -> theorem_pipeline/workspace/contexts/paper.txt`
+- Required output B (theorem-focused excerpt):
+  - `theorem_pipeline/workspace/contexts/<theorem_slug>_source_excerpt.txt`
+  - Example: `proposition2_source_excerpt.txt`
+- Keep both outputs:
+  - full extraction = reusable cache across multiple theorem proofs from the same paper;
+  - excerpt = focused context for the current theorem.
+- Reuse policy:
+  - if the full extraction file already exists and is still valid for the current PDF, reuse it instead of converting the PDF again.
+
+If input is not a PDF (prompt text, local `.txt`/`.md`/`.tex`, or fetched online source):
+- Skip PDF conversion.
+- Use the source as requested by the user.
+- Store a normalized local source artifact under `theorem_pipeline/workspace/contexts/` (for example, `<theorem_slug>_source.txt`).
+- Optionally store a focused excerpt as `<theorem_slug>_source_excerpt.txt` when useful for theorem-specific context.
+
+ASCII rewrites of common symbols are allowed when needed for robust editing/parsing.
+
+## 3. Create a Proof Run
+
+```bash
+uv run -m tproof.cli start-run --prompt-file ./workspace/prompts/fill_sorries.txt
+```
+
+This writes:
+- `data/runs/<run_id>/run.json`
+- `data/runs/<run_id>/run_brief.md`
+- snapshot of the Lean project for traceability
+
+## 4. Required Agent Routing
+
+Use two workers:
+
+1. Proof worker (math-heavy):
+   - profile: deep-thinking reasoning model for complex mathematics
+   - responsibility: theorem proving, decomposition, and difficult Lean proof terms.
+
+2. Ops worker (programming/reporting):
+   - profile: smaller coding-oriented model for implementation and reporting
+   - responsibility: scripts, logs, verification loops, metadata updates, concise run reports.
+
+## 5. Iterate Until Clean Verification
+
+After proof edits:
+
+```bash
+uv run -m tproof.cli reindex
+uv run -m tproof.cli verify
+```
+
+`verify` fails on:
+- `lake build` failures
+- any unresolved `sorry`
+- any `.lean`/`.md` final artifacts found under `workspace/staging/` (forbidden; move to `ProofWorkspace/Final/`)
+
+When done, set run status:
+
+```bash
+uv run -m tproof.cli set-status <run_id> COMPLETE --note "all goals proven and verified"
+```
+
+## 6. Final Artifact Placement and Sidecar Sketch Files (`.md`)
+
+Final theorem artifacts must be written only under:
+- `theorem_pipeline/workspace/lean_project/ProofWorkspace/Final/`
+
+Forbidden output location:
+- `workspace/staging/` for any final proof or sketch artifact.
+
+For every finalized Lean proof file, create a sibling Markdown sketch file:
+- Naming convention:
+  - full proof (Lean-safe filename): `ProofWorkspace/Final/<Name>Full.lean`
+  - sketch: `ProofWorkspace/Final/<Name>Sketch.md`
+  - example pair: `ProofWorkspace/Final/Proposition1Full.lean` and `ProofWorkspace/Final/Proposition1Sketch.md`
+- Keep sidecars in the same module directory so paper authors can trace them easily.
+- In sketch files, all mathematics must be written with LaTeX dollar syntax (`$...$` / `$$...$$`).
+- The `Proof Sketch` section must be fluent mathematical prose (paper style), not a numbered recipe.
+
+Recommended sidecar template:
+
+```md
+# <Theorem Name>
+
+## Statement
+Plain-language statement mapped to the Lean theorem name(s).
+
+## Assumptions
+- A1
+- A2
+- ...
+
+## Proof Sketch
+Write a concise, fluent paragraph (or short sequence of paragraphs) as a mathematician would explain the proof to another mathematician in a paper. Emphasize the key reductions and ideas, but avoid low-level proof script details.
+
+Use inline/display LaTeX where needed, for example:
+`By reducing the claim to $X$, applying $Y$, and combining with $Z$, we obtain the target bound $f(x) \le g(x)$ for all $x \in D$.`
+
+## Corollaries (if required)
+- help
+- match
+- upper-bound
+
+## Lean Artifacts
+- File: <path/to/ProofWorkspace/Final/NameFull.lean>
+- Theorems:
+  - <theorem_name_1>
+  - <theorem_name_2>
+```
+
+Compatibility note:
+- The pipeline indexes/checks only `*.lean` files (`reindex`, module discovery, and `sorry` scan), so `.md` sidecars do not affect Lean verification.
+
+## 7. Final Report Status Line
+
+Keep the existing report format, and append one additional final line:
+- `SUCCESS`
+- or `FAIL: <reason>`

package/skills/flywheel-prove/scripts/scaffold_pipeline.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Scaffold a local Lean theorem proving pipeline into a target repository.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def run(command: list[str], cwd: Path) -> None:
+    proc = subprocess.run(command, cwd=cwd, text=True, check=False)
+    if proc.returncode != 0:
+        raise RuntimeError(f"Command failed ({proc.returncode}): {' '.join(command)}")
+
+
+def scaffold(repo_root: Path, subdir: str, force: bool) -> Path:
+    skill_root = Path(__file__).resolve().parents[1]
+    template_dir = skill_root / "assets" / "pipeline_template"
+    if not template_dir.is_dir():
+        raise FileNotFoundError(f"Missing template directory: {template_dir}")
+
+    target = (repo_root / subdir).resolve()
+    if target.exists():
+        if not force:
+            raise FileExistsError(
+                f"Target already exists: {target}. Pass --force to replace it."
+            )
+        if target == repo_root.resolve():
+            raise RuntimeError("Refusing to delete repo root.")
+        shutil.rmtree(target)
+
+    shutil.copytree(template_dir, target)
+    return target
+
+
+def ensure_uv_available() -> None:
+    proc = subprocess.run(
+        ["uv", "--version"], capture_output=True, text=True, check=False
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(
+            "Missing `uv` on PATH. Install uv first: https://docs.astral.sh/uv/getting-started/installation/"
+        )
+
+
+def setup_env_with_uv(pipeline_dir: Path) -> None:
+    ensure_uv_available()
+    run(["uv", "sync"], cwd=pipeline_dir)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Scaffold local Lean theorem proving pipeline."
+    )
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=Path.cwd(),
+        help="Repository root where the pipeline folder will be created.",
+    )
+    parser.add_argument(
+        "--subdir",
+        type=str,
+        default="theorem_pipeline",
+        help="Subdirectory name for the pipeline workspace.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace target directory if it already exists.",
+    )
+    parser.add_argument(
+        "--setup-env",
+        action="store_true",
+        help="Run `uv sync` in the scaffolded pipeline directory.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    repo_root = args.repo_root.resolve()
+    repo_root.mkdir(parents=True, exist_ok=True)
+
+    pipeline_dir = scaffold(repo_root=repo_root, subdir=args.subdir, force=args.force)
+    if args.setup_env:
+        setup_env_with_uv(pipeline_dir)
+
+    print(f"[OK] Scaffolded pipeline at: {pipeline_dir}")
+    print("Next commands:")
+    print(f"  cd {pipeline_dir}")
+    if not args.setup_env:
+        print("  uv sync")
+    print("  uv run -m tproof.cli doctor")
+    print("  uv run -m tproof.cli init --build")
+    print(
+        "  uv run -m tproof.cli start-run --prompt-file ./workspace/prompts/fill_sorries.txt"
+    )
+    print("  uv run -m tproof.cli verify")
+    print("Optional wrappers:")
+    print("  macOS/Linux: ./bin/tproof doctor")
+    print("  Windows cmd: .\\bin\\tproof.cmd doctor")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/flywheel-reproduce/SKILL.md

@@ -57,8 +57,10 @@ Before execution, recover or establish these inputs:
    - Later reproduce passes must read the control node `content` first and continue from that persisted contract rather than from chat memory.
 3. Classify the source.
    - If the input is already a normalized Flywheel graph export, `flywheel_import_subgraph` may be appropriate.
-   - If it is a markdown wiki, README corpus, blog post, or paper, port it explicitly with node and artifact tools before execution.
-   - If it is a claim-bearing paper or benchmark result, split the work into explicit validation branches rather than treating the whole source as one flat note.
+   - Otherwise, route to one source reference in `references/` using the
+     `Source Type Routing` section below.
+   - Complete source decomposition from the selected reference before step 8
+     branch planning or execution.
 4. 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.
@@ -80,7 +82,7 @@ Before execution, recover or establish these inputs:
    - Prefer explicit validation branches such as baseline checks, mechanism or intermediate-signal checks, ablations, efficiency checks, robustness checks, failure analysis, and follow-up analysis branches after results land.
    - If the branch can run through Flywheel execution directly, use `flywheel_launch_execution` and inspect terminal status before commit.
 
-   - If the branch needs managed compute, use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants` or `flywheel_list_approval_sessions`, 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.
+   - If the branch needs managed compute, 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.
    - 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.
@@ -133,35 +135,38 @@ Canonical contract shape:
 
 The `Source or claim nodes under test` line is the recovery anchor for later validation passes. If multiple claim nodes are in scope, list the governing node ids or slugs explicitly.
 
-## Wiki Porting
+## Source Type Routing
 
-Use this guide when the source material is a markdown wiki, README corpus, or a Karpathy-style LLM wiki that should become Flywheel nodes. In the flywheel-reproduce skill, do this graphification pass before empirical execution starts.
+Route every non-normalized source through one reference file before
+graphification and validation planning.
 
-### Default Mapping
+Routing order:
 
-- One wiki page or stable concept -> one Flywheel node.
-- The main page markdown -> the node body/readme field (`content`).
-- A short synopsis of the page -> `summary`.
-- Images, PDFs, datasets, notebooks, code snippets, and other supporting files -> node artifacts.
-- Durable structural relationships -> graph edges.
-- Ordinary wiki hyperlinks -> remain markdown links inside the node body.
+1. Deterministic routing.
+2. Natural-language routing.
+3. Generic fallback.
 
-Do not try to preserve the source wiki as a file-first mirror inside Flywheel. Flywheel is node-first.
+Deterministic routing rules:
 
-### What The Model Should Do
+- Local `.pdf` files -> `references/source-paper.md`
+- `arxiv.org/abs/*`, `arxiv.org/pdf/*`, DOI URLs, direct PDF URLs -> `references/source-paper.md`
+- Markdown files, wiki exports, wiki-like repositories -> `references/source-wiki.md`
+- Blog/article domains and long-form article URLs -> `references/source-blog.md`
+- Local notes trees (Obsidian, Logseq, plain markdown note directories) -> `references/source-notes.md`
 
-Assume the model is expected to perform the port directly unless the user explicitly asks to build a dedicated importer.
+Natural-language routing rule:
 
-That means:
+- If deterministic routing is inconclusive, use user intent from prompt/context
+  (for example, "import this paper", "graph this wiki", "convert this blog
+  post", "port these research notes") and pick the matching source reference.
 
-1. Read the source pages and supporting files.
-2. Create or update nodes explicitly.
-3. Write the page body into node `content`.
-4. Publish supporting files as artifacts.
-5. Add only the graph edges that materially help reasoning or navigation.
-6. Split the claim-bearing work into explicit validation branches before execution.
+Generic fallback rule:
 
-Do not wait for a magical bulk-import surface if the available Flywheel primitives are already enough.
+- If deterministic and natural-language routing are both inconclusive, load
+  `references/source-generic.md`.
+
+After choosing a source type, load that reference and complete source
+decomposition before entering step 8 validation branch planning.
 
 ## `flywheel_import_subgraph`
 

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

@@ -2,7 +2,13 @@
   {
     "id": "claim-bearing-paper-with-no-budget-yet",
     "prompt": "Use $flywheel-reproduce to validate the central empirical claims from this paper in Flywheel. I have not given you a max budget yet, but I do want the source structured and the validation plan prepared.",
-    "expected_output": "Graphify the source and plan explicit validation branches, ask once for a hard max budget before any compute acquisition, and avoid empirical execution until the budget is explicit.",
+    "expected_output": "Create a parent paper node under the requested root, decompose the paper into section child nodes, keep section narratives in each child `content`, attach the PDF to the parent node, and stage explicit validation branch plans. Ask once for a hard max budget before any compute acquisition, and do not execute branches until the budget is explicit. Do NOT produce a single `insight` node with the PDF as the only artifact.",
+    "files": []
+  },
+  {
+    "id": "paper-pdf-decomposes-into-section-children",
+    "prompt": "Use $flywheel-reproduce on the paper PDF in the current folder, attach results under an existing root, plan validation branches, and do not launch execution yet.",
+    "expected_output": "Create a parent paper node under the root, add one child node per top-level paper section, place section narratives in child `content`, and attach the PDF artifact on the parent. Plan at least one explicit validation branch and keep execution unlaunched until budget gating is satisfied. Do NOT emit a single `insight` node with only a summary and the PDF artifact.",
     "files": []
   },
   {

package/skills/flywheel-reproduce/references/ARTIFACTS.md

@@ -43,7 +43,6 @@ Canonical artifact upload/finalize contract derived from `mcp_contract.py`.
 
 - Stale `expected_revision` on mutating calls returns `409` and requires explicit reconciliation.
 - Reusing an idempotency key with a different payload hash causes `409_conflict`.
-- Empirical `completed` commits must satisfy one of: `artifacts_non_empty`, `no_artifacts_reason_non_empty`.
 - Prepare item payloads must be structured objects; stringified JSON item payloads are invalid.
 - Uploading metadata wrappers instead of raw file bytes violates the upload contract.
 - Finalize requires a valid prepared batch token and staged uploads from that batch.

package/skills/flywheel-reproduce/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`)
@@ -132,10 +134,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`
@@ -173,7 +177,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-reproduce/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-reproduce/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).
@@ -77,20 +72,20 @@ 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_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 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
 
@@ -113,15 +108,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 +130,19 @@ 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_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).
-- `flywheel_compute_release`: release compute when no longer needed.
-- `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution lifecycle.
+- `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-reproduce/references/source-blog.md

@@ -0,0 +1,35 @@
+# Blog Source Reference
+
+Use this reference for blog posts and article-style URLs.
+
+## Source Detection
+
+Match this reference for sources from common blog/article domains or article-like HTML pages.
+
+## Acquisition
+
+- Fetch URL content.
+- Extract main article body and heading structure.
+
+## Decomposition
+
+- Short posts: one node is acceptable.
+- Long posts: parent article node plus section children by top-level headings.
+- Complete source decomposition before branch planning.
+
+## Content and Artifacts
+
+- Article narrative in node `content`.
+- Summary in `summary`.
+- Supporting media files as artifacts when available.
+
+## Edges
+
+- Use hierarchy edges when section children are created.
+- Avoid lateral interpretive edges by default.
+
+## Failure Behavior
+
+- If fetch or extraction fails, emit explicit failure and stop.
+
+These rules apply only when `$flywheel-reproduce` is the active skill.