@paradigma-inc/flywheel 0.1.19 → 0.1.26

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.

package/skills/flywheel-reproduce/references/source-generic.md

@@ -0,0 +1,30 @@
+# Generic Source Reference
+
+Use this fallback when source type cannot be confidently matched to paper, wiki, blog, or notes.
+
+## Fallback Trigger
+
+Activate this reference only after deterministic and natural-language routing fail to produce a confident match.
+
+## Acquisition
+
+- Ask once for missing source location when not recoverable.
+- Perform best-effort extraction from the provided source.
+
+## Decomposition
+
+- If top-level headings are available, create parent and section children.
+- If no structural cues are available, create one node with explicit summary of limitations.
+- Complete source decomposition before any validation branch planning.
+
+## Content and Artifacts
+
+- Keep extracted narrative in `content`.
+- Attach supporting files as artifacts.
+
+## Failure Behavior
+
+- If extraction fails, emit explicit failure and stop.
+- Do not silently produce an underspecified graph.
+
+These rules apply only when `$flywheel-reproduce` is the active skill.

package/skills/flywheel-reproduce/references/source-notes.md

@@ -0,0 +1,35 @@
+# Notes Source Reference
+
+Use this reference for local note directories such as Obsidian vaults, Logseq exports, or plain markdown note trees.
+
+## Source Detection
+
+Match this reference when source is a local notes corpus with many small markdown files.
+
+## Acquisition
+
+- Enumerate note files in requested scope.
+- Preserve folder and filename context.
+
+## Decomposition
+
+- Default: one note file -> one node.
+- Large note files: split by top-level headings when useful.
+- Complete decomposition before creating validation branches.
+
+## Content and Artifacts
+
+- Note text in `content`.
+- Concise note synopsis in `summary`.
+- Embedded local files become artifacts when relevant.
+
+## Edges
+
+- Add edges only for durable relationships (hierarchy, prerequisite, dependency).
+- Keep casual backlinks inside markdown.
+
+## Failure Behavior
+
+- If note files cannot be read, emit explicit failure with affected paths.
+
+These rules apply only when `$flywheel-reproduce` is the active skill.

package/skills/flywheel-reproduce/references/source-paper.md

@@ -0,0 +1,89 @@
+# Paper Source Reference
+
+Use this reference when the source is a paper PDF, arXiv page, DOI URL, or direct PDF URL.
+
+## Source Detection
+
+Match this reference when any of these are true:
+
+- Local file ends with `.pdf`.
+- URL matches `arxiv.org/abs/`.
+- URL matches `arxiv.org/pdf/`.
+- URL is a DOI resolver link (`doi.org/...`).
+- URL is a direct PDF link.
+
+## Acquisition Rules
+
+Acquire source content in this order:
+
+1. Local PDF path: read local file bytes and preserve original filename.
+2. arXiv HTML URL (`arxiv.org/abs/...` or `arxiv.org/html/...`): fetch page body and parse section structure from HTML.
+3. arXiv PDF URL (`arxiv.org/pdf/...`): download PDF bytes and treat as PDF input.
+4. DOI URL: resolve final landing page; if it exposes a PDF, download it, otherwise fetch the HTML body.
+5. Direct PDF URL: download PDF bytes.
+
+## Parsing Rules
+
+For PDF text extraction, use parser fallback chain exactly:
+
+`PyMuPDF -> pypdfium2 -> pypdf`
+
+- Try one parser at a time in that order.
+- Advance to the next parser only when the previous parser fails to extract usable text.
+- If all parsers fail, emit explicit failure and stop. Do not continue with partial guessed structure.
+- If all parsers fail, do not silently produce a single-summary node with a PDF artifact.
+
+License note:
+
+- PyMuPDF is AGPL-3.0. Artifex offers a commercial license when AGPL terms are not acceptable for downstream distribution.
+
+For arXiv HTML parsing, use LaTeXML selector boundaries:
+
+- Top-level sections: `section.ltx_section`
+- Top-level headings: `h2.ltx_title`
+- Subsections: `section.ltx_subsection`
+- Subsection headings: `h3.ltx_title`
+
+Do not use naive `section` selectors without class filtering.
+
+## Graph Decomposition Contract
+
+Default shape:
+
+- Create one parent paper node under the requested root.
+- Create one child node per detected top-level paper section.
+- Typical section set includes Abstract, Introduction, Methods, Results, Discussion, Conclusion, and Related Work when present.
+
+## Content Placement Contract
+
+- Parent title: paper title.
+- Parent summary: abstract or concise abstract-derived synopsis.
+- Parent content: one-paragraph orientation plus links/references to section children.
+- Child content: narrative for that section only.
+
+## Artifact Contract
+
+- Attach the paper PDF artifact to the parent paper node.
+- Attach extracted figures/tables to the section child where they appear, when extraction is feasible.
+
+## Edge Contract
+
+- Use hierarchy edges for paper parent -> section children.
+- Do not add lateral interpretive edges (`cites`, `builds-on`, `derived-from`) by default.
+
+## Insight Controller Contract
+
+- Single-paper one-shot import: no separate insight control node is created.
+- Multi-paper corpus import: create one insight control node above paper parent nodes.
+
+## Failure Contract
+
+- If acquisition fails, return explicit failure with the failing source variant and stop.
+- If all parsers fail, return explicit failure and stop.
+- Do not silently degrade to one summary node plus artifact-only output.
+
+## Reproduce Ordering Contract
+
+Finish paper decomposition before validation branch planning. Do not start step-8 branch execution planning until source decomposition is complete.
+
+These rules apply only when `$flywheel-reproduce` is the active skill.

package/skills/flywheel-reproduce/references/source-wiki.md

@@ -0,0 +1,36 @@
+# Wiki Source Reference
+
+Use this reference for markdown wiki-style corpora, README trees, GitHub wiki exports, and Notion markdown exports.
+
+## Source Detection
+
+Match this reference when source material is wiki-like markdown content with multiple linked pages.
+
+## Acquisition
+
+- Collect all relevant markdown pages in scope.
+- Preserve stable page identifiers from file paths or page titles.
+
+## Decomposition
+
+- One stable page or concept maps to one node by default.
+- Large pages may split by top-level headings when that improves readability.
+- Complete graphification before branch planning and execution.
+
+## Content and Artifacts
+
+- Main narrative goes into node `content`.
+- Short synopsis goes into `summary`.
+- Supporting files (images, PDFs, data files, notebooks) are node artifacts.
+
+## Edges
+
+- Promote only durable semantic relationships to graph edges.
+- Keep incidental hyperlinks in markdown body.
+
+## Failure Behavior
+
+- If pages are unreadable or missing, emit explicit failure and stop for that page.
+- Do not silently skip unreadable pages.
+
+These rules apply only when `$flywheel-reproduce` is the active skill.

package/skills/flywheel-to-graph/SKILL.md

@@ -44,9 +44,10 @@ Before authoring, recover or establish these inputs:
 1. Resolve the starting context.
    - Start from the provided source material or explicit source nodes.
    - Resolve governing nodes in this order: explicit node ids/slugs, explicitly named current context, focused or recently referenced nodes, then ask the user if nothing stable is recoverable.
-2. Classify the input.
+2. Classify the input through source-type routing.
    - If it is already a normalized Flywheel graph export, `flywheel_import_subgraph` may be appropriate.
-   - If it is a markdown/wiki/blog/README corpus, paper, or research note set, port it explicitly with node and artifact tools.
+   - Otherwise, route to one source reference in `references/` using the `Source Type Routing` section below.
+   - Complete source routing before step 3 node mapping.
 3. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
    - Create a new node with `flywheel_stage_node_create` when needed.
@@ -107,34 +108,38 @@ Canonical contract shape:
 
 The `Source corpus` and `Intended scope` lines are the recovery anchors for later authoring passes.
 
-## 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.
+Route every non-normalized source through one reference file before authoring.
 
-### 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.
+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 follow its acquisition,
+parsing, decomposition, artifact, and failure contracts for the rest of the
+authoring pass.
 
 ## `flywheel_import_subgraph`
 

package/skills/flywheel-to-graph/evals/evals.json

@@ -14,7 +14,13 @@
   {
     "id": "claim-bearing-paper-without-execution",
     "prompt": "Use $flywheel-to-graph to structure this claim-bearing paper into Flywheel nodes and artifacts, but do not run any validation branches yet.",
-    "expected_output": "Port the paper into nodes, artifacts, and durable edges without hidden execution or compute acquisition, leaving any later empirical validation to `$flywheel-reproduce`.",
+    "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 avoid hidden execution or compute acquisition. 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-to-graph on the paper PDF in the current folder and attach the result under an existing root node.",
+    "expected_output": "Create a parent paper node under the root, add one child node per top-level paper section (for example Abstract, Introduction, Methods, Results, Discussion, Conclusion), place each section narrative in child `content`, and attach the PDF artifact on the parent. Do NOT emit a single `insight` node with only a summary and the PDF artifact.",
     "files": []
   }
 ]

package/skills/flywheel-to-graph/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-to-graph/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-to-graph/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-to-graph/references/source-blog.md

@@ -0,0 +1,34 @@
+# 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.
+
+## 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-to-graph` is the active skill.

package/skills/flywheel-to-graph/references/source-generic.md

@@ -0,0 +1,29 @@
+# Generic Source Reference
+
+Use this fallback when source type cannot be confidently matched to paper, wiki, blog, or notes.
+
+## Fallback Trigger
+
+Activate this reference only after deterministic and natural-language routing fail to produce a confident match.
+
+## Acquisition
+
+- Ask once for missing source location when not recoverable.
+- Perform best-effort extraction from the provided source.
+
+## Decomposition
+
+- If top-level headings are available, create parent and section children.
+- If no structural cues are available, create one node with explicit summary of limitations.
+
+## Content and Artifacts
+
+- Keep extracted narrative in `content`.
+- Attach supporting files as artifacts.
+
+## Failure Behavior
+
+- If extraction fails, emit explicit failure and stop.
+- Do not silently produce an underspecified graph.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/skills/flywheel-to-graph/references/source-notes.md

@@ -0,0 +1,34 @@
+# Notes Source Reference
+
+Use this reference for local note directories such as Obsidian vaults, Logseq exports, or plain markdown note trees.
+
+## Source Detection
+
+Match this reference when source is a local notes corpus with many small markdown files.
+
+## Acquisition
+
+- Enumerate note files in requested scope.
+- Preserve folder and filename context.
+
+## Decomposition
+
+- Default: one note file -> one node.
+- Large note files: split by top-level headings when useful.
+
+## Content and Artifacts
+
+- Note text in `content`.
+- Concise note synopsis in `summary`.
+- Embedded local files become artifacts when relevant.
+
+## Edges
+
+- Add edges only for durable relationships (hierarchy, prerequisite, dependency).
+- Keep casual backlinks inside markdown.
+
+## Failure Behavior
+
+- If note files cannot be read, emit explicit failure with affected paths.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.